home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / custom.info.z / custom.info
Encoding:
GNU Info File  |  1998-05-21  |  13.3 KB  |  391 lines
  1. This is Info file ../info/custom.info, produced by Makeinfo version
  2. 1.68 from the input file custom.texi.
  3.  
  4. 
  5. File: custom.info,  Node: Top,  Next: Declaring Groups,  Prev: (dir),  Up: (dir)
  6.  
  7. The Customization Library
  8. *************************
  9.  
  10.    This manual describes how to declare customization groups, variables,
  11. and faces.  It doesn't contain any examples, but please look at the file
  12. `cus-edit.el' which contains many declarations you can learn from.
  13.  
  14. * Menu:
  15.  
  16. * Declaring Groups::
  17. * Declaring Variables::
  18. * Declaring Faces::
  19. * Usage for Package Authors::
  20. * Utilities::
  21. * The Init File::
  22. * Wishlist::
  23.  
  24.    All the customization declarations can be changes by keyword
  25. arguments.  Groups, variables, and faces all share these common
  26. keywords:
  27.  
  28. `:group'
  29.      VALUE should be a customization group.  Add SYMBOL to that group.
  30.  
  31. `:link'
  32.      VALUE should be a widget type.  Add VALUE to the external links
  33.      for this customization option.  Useful widget types include
  34.      `custom-manual', `info-link', and `url-link'.
  35.  
  36. `:load'
  37.      Add VALUE to the files that should be loaded before displaying
  38.      this customization option.  The value should be either a string,
  39.      which should be a string which will be loaded with `load-library'
  40.      unless present in `load-history', or a symbol which will be loaded
  41.      with `require'.
  42.  
  43. `:tag'
  44.      VALUE should be a short string used for identifying the option in
  45.      customization menus and buffers.  By default the tag will be
  46.      automatically created from the options name.
  47.  
  48. 
  49. File: custom.info,  Node: Declaring Groups,  Next: Declaring Variables,  Prev: Top,  Up: Top
  50.  
  51. Declaring Groups
  52. ================
  53.  
  54.    Use `defgroup' to declare new customization groups.
  55.  
  56.  - Function: defgroup SYMBOL MEMBERS DOC [KEYWORD VALUE]...
  57.      Declare SYMBOL as a customization group containing MEMBERS.
  58.      SYMBOL does not need to be quoted.
  59.  
  60.      DOC is the group documentation.
  61.  
  62.      MEMBERS should be an alist of the form ((NAME WIDGET)...) where
  63.      NAME is a symbol and WIDGET is a widget for editing that symbol.
  64.      Useful widgets are `custom-variable' for editing variables,
  65.      `custom-face' for editing faces, and `custom-group' for editing
  66.      groups.
  67.  
  68.      Internally, custom uses the symbol property `custom-group' to keep
  69.      track of the group members, and `group-documentation' for the
  70.      documentation string.
  71.  
  72.      The following additional KEYWORD's are defined:
  73.  
  74.     `:prefix'
  75.           VALUE should be a string.  If the string is a prefix for the
  76.           name of a member of the group, that prefix will be ignored
  77.           when creating a tag for that member.
  78.  
  79. 
  80. File: custom.info,  Node: Declaring Variables,  Next: Declaring Faces,  Prev: Declaring Groups,  Up: Top
  81.  
  82. Declaring Variables
  83. ===================
  84.  
  85.    Use `defcustom' to declare user editable variables.
  86.  
  87.  - Function: defcustom SYMBOL VALUE DOC [KEYWORD VALUE]...
  88.      Declare SYMBOL as a customizable variable that defaults to VALUE.
  89.      Neither SYMBOL nor VALUE needs to be quoted.  If SYMBOL is not
  90.      already bound, initialize it to VALUE.
  91.  
  92.      DOC is the variable documentation.
  93.  
  94.      The following additional KEYWORD's are defined:
  95.  
  96.     `:type'
  97.           VALUE should be a widget type.
  98.  
  99.     `:options'
  100.           VALUE should be a list of possible members of the specified
  101.           type.  For hooks, this is a list of function names.
  102.  
  103.     `:initialize'
  104.           VALUE should be a function used to initialize the variable.
  105.           It takes two arguments, the symbol and value given in the
  106.           `defcustom' call.  Some predefined functions are:
  107.  
  108.          `custom-initialize-set'
  109.                Use the `:set' method to initialize the variable.  Do not
  110.                initialize it if already bound.  This is the default
  111.                `:initialize' method.
  112.  
  113.          `custom-initialize-default'
  114.                Always use `set-default' to initialize the variable,
  115.                even if a `:set' method has been specified.
  116.  
  117.          `custom-initialize-reset'
  118.                If the variable is already bound, reset it by calling
  119.                the `:set' method with the value returned by the `:get'
  120.                method.
  121.  
  122.          `custom-initialize-changed'
  123.                Like `custom-initialize-reset', but use `set-default' to
  124.                initialize the variable if it is not bound and has not
  125.                been set already.
  126.  
  127.     `:set'
  128.           VALUE should be a function to set the value of the symbol.  It
  129.           takes two arguments, the symbol to set and the value to give
  130.           it.  The default is `set-default'.
  131.  
  132.     `:get'
  133.           VALUE should be a function to extract the value of symbol.
  134.           The function takes one argument, a symbol, and should return
  135.           the current value for that symbol.  The default is
  136.           `default-value'.
  137.  
  138.     `:require'
  139.           VALUE should be a feature symbol.  Each feature will be
  140.           required when the `defcustom' is evaluated, or when Emacs is
  141.           started if the user has saved this option.
  142.  
  143.      *Note Sexp Types: (widget)Sexp Types, for information about
  144.      widgets to use together with the `:type' keyword.
  145.  
  146.    Internally, custom uses the symbol property `custom-type' to keep
  147. track of the variables type, `standard-value' for the program specified
  148. default value, `saved-value' for a value saved by the user, and
  149. `variable-documentation' for the documentation string.
  150.  
  151.    Use `custom-add-option' to specify that a specific function is
  152. useful as an member of a hook.
  153.  
  154.  - Function: custom-add-option SYMBOL OPTION
  155.      To the variable SYMBOL add OPTION.
  156.  
  157.      If SYMBOL is a hook variable, OPTION should be a hook member.  For
  158.      other types variables, the effect is undefined."
  159.  
  160. 
  161. File: custom.info,  Node: Declaring Faces,  Next: Usage for Package Authors,  Prev: Declaring Variables,  Up: Top
  162.  
  163. Declaring Faces
  164. ===============
  165.  
  166.    Faces are declared with `defface'.
  167.  
  168.  - Function: defface FACE SPEC DOC [KEYWORD VALUE]...
  169.      Declare FACE as a customizable face that defaults to SPEC.  FACE
  170.      does not need to be quoted.
  171.  
  172.      If FACE has been set with `custom-set-face', set the face
  173.      attributes as specified by that function, otherwise set the face
  174.      attributes according to SPEC.
  175.  
  176.      DOC is the face documentation.
  177.  
  178.      SPEC should be an alist of the form `((DISPLAY ATTS)...)'.
  179.  
  180.      ATTS is a list of face attributes and their values.  The possible
  181.      attributes are defined in the variable `custom-face-attributes'.
  182.  
  183.      The ATTS of the first entry in SPEC where the DISPLAY matches the
  184.      frame should take effect in that frame.  DISPLAY can either be the
  185.      symbol `t', which will match all frames, or an alist of the form
  186.      `((REQ ITEM...)...)'
  187.  
  188.      For the DISPLAY to match a FRAME, the REQ property of the frame
  189.      must match one of the ITEM.  The following REQ are defined:
  190.  
  191.     `type'
  192.           (the value of (window-system))
  193.           Should be one of `x' or `tty'.
  194.  
  195.     `class'
  196.           (the frame's color support)
  197.           Should be one of `color', `grayscale', or `mono'.
  198.  
  199.     `background'
  200.           (what color is used for the background text)
  201.           Should be one of `light' or `dark'.
  202.  
  203.      Internally, custom uses the symbol property `face-defface-spec' for
  204.      the program specified default face properties, `saved-face' for
  205.      properties saved by the user, and `face-documentation' for the
  206.      documentation string.
  207.  
  208.  
  209. 
  210. File: custom.info,  Node: Usage for Package Authors,  Next: Utilities,  Prev: Declaring Faces,  Up: Top
  211.  
  212. Usage for Package Authors
  213. =========================
  214.  
  215.    The recommended usage for the author of a typical emacs lisp package
  216. is to create one group identifying the package, and make all user
  217. options and faces members of that group.  If the package has more than
  218. around 20 such options, they should be divided into a number of
  219. subgroups, with each subgroup being member of the top level group.
  220.  
  221.    The top level group for the package should itself be member of one or
  222. more of the standard customization groups.  There exists a group for
  223. each *finder* keyword.  Press `C-h p' to see a list of finder keywords,
  224. and add you group to each of them, using the `:group' keyword.
  225.  
  226. 
  227. File: custom.info,  Node: Utilities,  Next: The Init File,  Prev: Usage for Package Authors,  Up: Top
  228.  
  229. Utilities
  230. =========
  231.  
  232.    These utilities can come in handy when adding customization support.
  233.  
  234.  - Widget: custom-manual
  235.      Widget type for specifying the info manual entry for a
  236.      customization option.  It takes one argument, an info address.
  237.  
  238.  - Function: custom-add-to-group GROUP MEMBER WIDGET
  239.      To existing GROUP add a new MEMBER of type WIDGET, If there
  240.      already is an entry for that member, overwrite it.
  241.  
  242.  - Function: custom-add-link SYMBOL WIDGET
  243.      To the custom option SYMBOL add the link WIDGET.
  244.  
  245.  - Function: custom-add-load SYMBOL LOAD
  246.      To the custom option SYMBOL add the dependency LOAD.  LOAD should
  247.      be either a library file name, or a feature name.
  248.  
  249.  - Function: customize-menu-create SYMBOL &optional NAME
  250.      Create menu for customization group SYMBOL.  If optional NAME is
  251.      given, use that as the name of the menu.  Otherwise the menu will
  252.      be named `Customize'.  The menu is in a format applicable to
  253.      `easy-menu-define'.
  254.  
  255. 
  256. File: custom.info,  Node: The Init File,  Next: Wishlist,  Prev: Utilities,  Up: Top
  257.  
  258. The Init File
  259. =============
  260.  
  261.    When you save the customizations, call to `custom-set-variables',
  262. `custom-set-faces' are inserted into the file specified by
  263. `custom-file'.  By default `custom-file' is your `.emacs' file.  If you
  264. use another file, you must explicitly load it yourself.  The two
  265. functions will initialize variables and faces as you have specified.
  266.  
  267. 
  268. File: custom.info,  Node: Wishlist,  Prev: The Init File,  Up: Top
  269.  
  270. Wishlist
  271. ========
  272.  
  273.    * Better support for keyboard operations in the customize buffer.
  274.  
  275.    * Integrate with `w3' so you can get customization buffers with much
  276.      better formatting.  I'm thinking about adding a
  277.      <custom>name</custom> tag.  The latest w3 have some support for
  278.      this, so come up with a convincing example.
  279.  
  280.    * Add an `examples' section, with explained examples of custom type
  281.      definitions.
  282.  
  283.    * Support selectable color themes.  I.e., change many faces by
  284.      setting one variable.
  285.  
  286.    * Support undo using lmi's `gnus-undo.el'.
  287.  
  288.    * Make it possible to append to `choice', `radio', and `set' options.
  289.  
  290.    * Ask whether set or modified variables should be saved in
  291.      `kill-buffer-hook'.
  292.  
  293.      Ditto for `kill-emacs-query-functions'.
  294.  
  295.    * Command to check if there are any customization options that does
  296.      not belong to an existing group.
  297.  
  298.    * Optionally disable the point-cursor and instead highlight the
  299.      selected item in XEmacs.  This is like the *Completions* buffer in
  300.      XEmacs.  Suggested by Jens Lautenbacher
  301.      `<jens@lemming0.lem.uni-karlsruhe.de>'.
  302.  
  303.    * Explain why it is necessary that all choices have different default
  304.      values.
  305.  
  306.    * Make it possible to include a comment/remark/annotation when
  307.      saving an option.
  308.  
  309.    * Add some direct support for meta variables, i.e. make it possible
  310.      to specify that this variable should be reset when that variable is
  311.      changed.
  312.  
  313.    * Add tutorial.
  314.  
  315.    * Describe the `:type' syntax in this manual.
  316.  
  317.    * Find a place is this manual for the following text:
  318.  
  319.      *Radio vs. Buttons*
  320.  
  321.      Use a radio if you can't find a good way to describe the item in
  322.      the choice menu text.  I.e. it is better to use a radio if you
  323.      expect the user would otherwise manually select each item from the
  324.      choice menu in turn to see what it expands too.
  325.  
  326.      Avoid radios if some of the items expands to complex structures.
  327.  
  328.      I mostly use radios when most of the items are of type
  329.      `function-item' or `variable-item'.
  330.  
  331.    * Update customize buffers when `custom-set-variable' or
  332.      `custom-save-customized' is called.
  333.  
  334.    * Better handling of saved but uninitialized items.
  335.  
  336.    * Detect when faces have been changed outside customize.
  337.  
  338.    * Enable mouse help in Emacs by default.
  339.  
  340.    * Add an easy way to display the standard settings when an item is
  341.      modified.
  342.  
  343.    * See if it is feasible to scan files for customization information
  344.      instead of loading them,
  345.  
  346.    * Add hint message when user push a non-pushable tag.
  347.  
  348.      Suggest that the user unhide if hidden, and edit the value directly
  349.      otherwise.
  350.  
  351.    * Use checkboxes and radio buttons in the state menus.
  352.  
  353.    * Add option to hide `[hide]' for short options.  Default, on.
  354.  
  355.    * Add option to hide `[state]' for options with their standard
  356.      settings.
  357.  
  358.    * There should be a way to specify site defaults for user options.
  359.  
  360.    * There should be more buffer styles.  The default `nested style,
  361.      the old `outline' style, a `numeric' style with numbers instead of
  362.      stars, an `empty' style with just the group name, and `compact'
  363.      with only one line per item.
  364.  
  365.    * Newline and tab should be displayed as `^J' and `^I' in the
  366.      `regexp' and `file' widgets.  I think this can be done in XEmacs
  367.      by adding a display table to the face.
  368.  
  369.    * Use glyphs to draw the `customize-browse' tree.
  370.  
  371.      Add echo and balloon help.  You should be able to read the
  372.      documentation simply by moving the mouse pointer above the name.
  373.  
  374.      Add parent links.
  375.  
  376.      Add colors.
  377.  
  378.  
  379. 
  380. Tag Table:
  381. Node: Top107
  382. Node: Declaring Groups1528
  383. Node: Declaring Variables2629
  384. Node: Declaring Faces5720
  385. Node: Usage for Package Authors7418
  386. Node: Utilities8197
  387. Node: The Init File9281
  388. Node: Wishlist9733
  389. 
  390. End Tag Table
  391.